Skip to content

fix: make layer toggles, stress slider, and feature popup keyboard and screen reader accessible (#4) - #16

Merged
GeoBradDev merged 5 commits into
mainfrom
issue-4-keyboard-screen-reader-a11y
Nov 7, 2026
Merged

GeoBradDev merged 5 commits into
mainfrom
issue-4-keyboard-screen-reader-a11y

Conversation

@GeoBradDev

Copy link
Copy Markdown
Owner

Makes the layer panel and the feature popup work with a keyboard and a screen reader.

  • Layer toggles (Airports, Sea Ports, and Heatmap when WebGPU is available): the native checkboxes are now hidden with a .visually-hidden utility instead of display: none, so they are back in the Tab order and the accessibility tree. Each one is named " layer", for example "Airports layer". The decorative dot and the ON/OFF text are aria-hidden, since the checked state already says it. A focused row shows an inset 2px accent outline (.layer-row:has(input:focus-visible)).
  • Stress slider: named "Stress test point count", with aria-valuetext such as "500,000 points". outline: none is replaced by a :focus-visible outline.
  • Feature popup: role="dialog", labelled by its "FEATURE INTEL" title. Focus moves to the dialog when it opens, and Escape closes it. On close, focus goes back to the element that had it before the popup opened, as long as focus was still inside the dialog. If the user has moved focus to another control, it stays there. The close button is named "Close", its glyph is aria-hidden, it has type="button", and it has a focus outline.
  • @testing-library/user-event is added as a dev dependency so the tests can send real Tab, Space, Enter and Escape key presses.

Not in this PR:

Plan

docs/plans/2026-11-07-issue-4-keyboard-screen-reader-a11y.md, committed in 5b4bcdf. Changes made during implementation, all recorded under the plan's Deviations:

  • Slider arrow-key test: user-event 14 in jsdom cannot step a range input with arrow keys. The unit test sends the one-step change a browser makes instead, and real arrow keys were checked in the browser.
  • Focus return (criterion 4): narrowed after review. Focus returns to the earlier element only when it was inside the dialog at close.
  • Close button: type="button" added.

Test evidence

Gate on 31b496a, run in order, all exit 0:

Command Result
npm ci 0 vulnerabilities
npm run lint no output
npm test 14 files, 106 tests passed (87 on main)
npm run build built; the chunk-size warning was already there on main
npm audit --omit=dev --audit-level=high 0 vulnerabilities

TDD:

  • 5d2e41c: the new tests committed alone and red. 16 failed, each for the expected reason.
  • 6a012f1: those tests pass.
  • 94fd4e9: a failing test for the focus-return bug, committed alone and red. Focus ended on "Opener" instead of "Elsewhere".
  • 31b496a: that test passes.

Lighthouse accessibility (lighthouse 12, headless Chrome, vite preview of the production build):

Build Score Failing audits
Before, main 10731f7 0.95 1: label on the stress-test range input
After, 6a012f1 1.0 none
After, 31b496a (rerun by the verifier) 1.0 none

There are no label or name failures. The hidden checkboxes were not flagged before because display: none took them out of the audit entirely.

Live drive in Chrome against vite preview, by the implementer and separately by a fresh verifier:

  • Tab order: from page start, focus goes map canvas, attribution toggle and links, "Airports layer", "Sea Ports layer", then "Stress test point count". With the popup open, Tab from the dialog reaches "Close".
  • Focus rings: each control shows a visible 2px accent outline, and none is clipped by the panel's overflow: hidden. Clicking a row with the mouse shows no ring.
  • Space: Space on a layer row toggles the layer. ON/OFF flips, the points leave the map, and the footer goes from ACTIVE 2/2 to 1/2. A mouse click still toggles the row.
  • Slider: ArrowRight steps the slider by 100,000, and aria-valuetext and the "500K PTS" readout follow. Home resets it to 0.
  • Accessibility tree: shows checkbox "Airports layer", checkbox "Sea Ports layer", slider "Stress test point count", a dialog labelled by "FEATURE INTEL", and button "Close".
  • Popup: clicking an airport opens it with the dialog focused. Clicking a second airport switches the content without moving focus. Escape, or Enter on Close, closes it and focus returns to the map canvas, which had focus before it opened. With the popup open, Tab or Shift+Tab to a layer checkbox and then Escape closes it, and focus stays on the checkbox.
  • Neighboring flows: map pan and zoom and the GPU info bar still work.
  • Not driven live: the test browser had no WebGPU, so the Heatmap toggle did not appear. Unit tests cover it (getByRole('checkbox', { name: 'Heatmap layer' })).

Review findings

  • Fixed: the popup cleanup always moved focus back to its opener, even after the user had tabbed into the layer panel. Pressing Escape there sent focus to the map. Raised by both the Claude finder and the Fable finder. Fixed in 94fd4e9 (red test) and 31b496a.
  • Fixed in the plan: type="button" on Close was not in the plan (Fable finder). It is now recorded there.
  • Dismissed: a delta finder (Claude) noted that a click on non-focusable chrome leaves focus on body, and Escape then moves focus to the opener. Focus on body means focus is lost, not placed somewhere. Moving it back to the opener avoids losing focus (WCAG 2.4.3), and leaving it on body would be worse for keyboard users.
  • Left as notes:
    • The Escape handler ignores isComposing and defaultPrevented. No other Escape handler exists on the page.
    • The slider ring is drawn around the 2px track, so the thumb crosses it. Sizing belongs to Secondary text fails WCAG contrast (2.48:1) and controls are below 24px target size #7.
    • The dialog's own focus ring rarely shows, because the popup only opens from a pointer click.
    • Switching features while the popup is open is not announced.
  • Verifier (fresh context): no findings.

Docs reconciled

  • README.md: no change needed. Nothing in it describes the controls' keyboard or screen reader behavior.
  • CLAUDE.md: no change needed. The Testing Library rule still holds, and user-event is part of Testing Library.
  • ADR: none.

Out of scope, seen during this work: the stress count readout ("0 PTS") is cut off at the panel's right edge on main as well. The range input keeps Chrome's default width of about 129px, so 129 + 8 gap + 56 min-width comes to more than the panel's roughly 172px of usable width (src/index.css .stress-row, .stress-count). This probably belongs with #5 or #7.

Closes #4

🤖 Generated with Claude Code

https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf

GeoBradDev and others added 5 commits November 7, 2026 16:36
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf
…d popup (#4)

Adds @testing-library/user-event as a devDependency for real Tab, Space,
Enter, and Escape sequences. Records in the plan that user-event cannot
step range inputs with arrow keys, so the slider test dispatches the
one-step change and arrow keys are verified in the live drive.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf
…d screen reader accessible (#4)

Layer checkboxes are visually hidden instead of display none and named
"<Label> layer"; the stress slider is named and exposes aria-valuetext.
The feature popup is a dialog labelled by its title that takes focus on
open, closes on Escape, and returns focus on close. Adds focus-visible
outlines in the accent color for rows, slider, popup, and close button.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf
When the user has moved focus outside the non-modal popup, closing it
must not pull focus back to the element focused before it opened.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf
…#4)

The non-modal popup closes on Escape from anywhere, so always refocusing
the saved element pulled focus away from controls the user had moved to.
Cleanup now restores focus only when it fell back to body because the
dialog node was removed. Records this and the close button type="button"
in the plan.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AELE7jB1i3uqqrHu3SjJjf
@GeoBradDev
GeoBradDev merged commit 885dcce into main Nov 7, 2026
1 check passed
@GeoBradDev
GeoBradDev deleted the issue-4-keyboard-screen-reader-a11y branch November 7, 2026 22:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Layer toggles, stress slider, and feature popup are not keyboard or screen reader accessible

1 participant